package org.springframework.social.kaixin.api;

import java.util.List;

import org.springframework.social.ApiException;
import org.springframework.social.MissingAuthorizationException;
import org.springframework.social.kaixin.api.impl.User;

public interface FriendOperations {

	/**
	 * Retrieves a list of custom friend lists belonging to the authenticated user.
	 * Requires "friends_records" permission.
	 * @return a list {@link Users}s, each representing a friend for the user, or an empty list if not available.
	 * @throws ApiException if there is an error while communicating with Kaixin.
	 * @throws MissingAuthorizationException if KaixinTemplate was not created with an access token.
	 */
	List<User> getFriendLists();

	/**
	 * Retrieves a list of the authenticating user's friends' IDs.
	 * Requires "friends_records" permission.
	 * @return a list of Strings, where each entry is the ID of one of the user's friends.
	 * @throws ApiException if there is an error while communicating with Kaixin.
	 * @throws MissingAuthorizationException if KaixinTemplate was not created with an access token.
	 */
	List<String> getFriendIds();
	
	/**
	 * Retrieves profile data for the authenticated user's friends.
	 * Requires "friends_records" permission.
	 * @return a {@link User}, representing a friend of the user.
	 * @throws ApiException if there is an error while communicating with Kaixin.
	 * @throws MissingAuthorizationException if KaixinTemplate was not created with an access token.
	 */
	User getMyInfo(String field);
	
}
